home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / Eval.3 < prev    next >
Text File  |  1995-07-17  |  9KB  |  301 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/Eval.3,v 1.13 93/04/03 16:40:04 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_Eval tclc 7.0
  206. .BS
  207. .SH NAME
  208. Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. int
  214. .VS
  215. \fBTcl_Eval\fR(\fIinterp, cmd\fR)
  216. .VE
  217. .sp
  218. int
  219. \fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
  220. .sp
  221. int
  222. \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
  223. .sp
  224. int
  225. \fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
  226. .SH ARGUMENTS
  227. .AS Tcl_Interp **termPtr;
  228. .AP Tcl_Interp *interp in
  229. Interpreter in which to execute the command.  String result will be
  230. stored in \fIinterp->result\fR.
  231. .AP char *cmd in
  232. Command (or sequence of commands) to execute.  Must be in writable
  233. memory (\fBTcl_Eval\fR makes temporary modifications to the command).
  234. .AP char *string in
  235. String forming part of Tcl command.
  236. .AP char *fileName in
  237. Name of file containing Tcl command string.
  238. .BE
  239.  
  240. .SH DESCRIPTION
  241. .PP
  242. All four of these procedures execute Tcl commands.
  243. \fBTcl_Eval\fR is the core procedure:  it parses commands
  244. from \fIcmd\fR and executes them in
  245. .VS
  246. order until either an error occurs or it reaches the end of the string.
  247. .VE
  248. The return value from \fBTcl_Eval\fR is one
  249. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  250. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  251. a string with additional information (result value or error message).
  252. This return information corresponds to the last command executed from
  253. \fIcmd\fR.
  254. .PP
  255. \fBTcl_VarEval\fR takes any number of string arguments
  256. of any length, concatenates
  257. them into a single string, then calls \fBTcl_Eval\fR to
  258. execute that string as a Tcl command.
  259. It returns the result of the command and also modifies
  260. \fIinterp->result\fR in the usual fashion for Tcl commands.  The
  261. last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
  262. of arguments.
  263. .PP
  264. \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
  265. its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
  266. a standard Tcl result that reflects the result of evaluating the
  267. file.
  268. If the file couldn't be read then a Tcl error is returned to describe
  269. why the file couldn't be read.
  270. .PP
  271. \fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
  272. processes the command at global level.
  273. This means that the variable context for the command consists of
  274. global variables only (it ignores any Tcl procedure that is active).
  275. This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
  276. .PP
  277. During the processing of a Tcl command it is legal to make nested
  278. calls to evaluate other commands (this is how conditionals, loops,
  279. and procedures are implemented).
  280. If a code other than
  281. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  282. caller should normally return immediately, passing that same
  283. return code back to its caller, and so on until the top-level application is
  284. reached.  A few commands, like \fBfor\fR, will check for certain
  285. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  286. specially without returning.
  287. .PP
  288. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  289. in progress for \fIinterp\fR.
  290. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  291. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  292. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  293. and sets \fIinterp->result\fR to point to an error message indicating that
  294. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  295. invoked in an inappropriate place.  This means that top-level
  296. applications should never see a return code from \fBTcl_Eval\fR other then
  297. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  298.  
  299. .SH KEYWORDS
  300. command, execute, file, global, interpreter, variable
  301.